'\" t
.TH "ORG\&.FREEDESKTOP\&.MACHINE1" "5" "" "systemd 249" "org.freedesktop.machine1"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
org.freedesktop.machine1 \- The D\-Bus interface of systemd\-machined
.SH "INTRODUCTION"
.PP
\fBsystemd-machined.service\fR(8)
is a system service that keeps track of locally running virtual machines and containers\&. This page describes the D\-Bus interface\&.
.SH "THE MANAGER OBJECT"
.PP
The service exposes the following interfaces on the Manager object on the bus:
.sp
.if n \{\
.RS 4
.\}
.nf
node /org/freedesktop/machine1 {
  interface org\&.freedesktop\&.machine1\&.Manager {
    methods:
      GetMachine(in  s name,
                 out o machine);
      GetImage(in  s name,
               out o image);
      GetMachineByPID(in  u pid,
                      out o machine);
      ListMachines(out a(ssso) machines);
      ListImages(out a(ssbttto) images);
      CreateMachine(in  s name,
                    in  ay id,
                    in  s service,
                    in  s class,
                    in  u leader,
                    in  s root_directory,
                    in  a(sv) scope_properties,
                    out o path);
      CreateMachineWithNetwork(in  s name,
                               in  ay id,
                               in  s service,
                               in  s class,
                               in  u leader,
                               in  s root_directory,
                               in  ai ifindices,
                               in  a(sv) scope_properties,
                               out o path);
      RegisterMachine(in  s name,
                      in  ay id,
                      in  s service,
                      in  s class,
                      in  u leader,
                      in  s root_directory,
                      out o path);
      RegisterMachineWithNetwork(in  s name,
                                 in  ay id,
                                 in  s service,
                                 in  s class,
                                 in  u leader,
                                 in  s root_directory,
                                 in  ai ifindices,
                                 out o path);
      UnregisterMachine(in  s name);
      TerminateMachine(in  s id);
      KillMachine(in  s name,
                  in  s who,
                  in  i signal);
      GetMachineAddresses(in  s name,
                          out a(iay) addresses);
      GetMachineOSRelease(in  s name,
                          out a{ss} fields);
      OpenMachinePTY(in  s name,
                     out h pty,
                     out s pty_path);
      OpenMachineLogin(in  s name,
                       out h pty,
                       out s pty_path);
      OpenMachineShell(in  s name,
                       in  s user,
                       in  s path,
                       in  as args,
                       in  as environment,
                       out h pty,
                       out s pty_path);
      BindMountMachine(in  s name,
                       in  s source,
                       in  s destination,
                       in  b read_only,
                       in  b mkdir);
      CopyFromMachine(in  s name,
                      in  s source,
                      in  s destination);
      CopyToMachine(in  s name,
                    in  s source,
                    in  s destination);
      OpenMachineRootDirectory(in  s name,
                               out h fd);
      GetMachineUIDShift(in  s name,
                         out u shift);
      RemoveImage(in  s name);
      RenameImage(in  s name,
                  in  s new_name);
      CloneImage(in  s name,
                 in  s new_name,
                 in  b read_only);
      MarkImageReadOnly(in  s name,
                        in  b read_only);
      GetImageHostname(in  s name,
                       out s hostname);
      GetImageMachineID(in  s name,
                        out ay id);
      GetImageMachineInfo(in  s name,
                          out a{ss} machine_info);
      GetImageOSRelease(in  s name,
                        out a{ss} os_release);
      SetPoolLimit(in  t size);
      SetImageLimit(in  s name,
                    in  t size);
      CleanPool(in  s mode,
                out a(st) images);
      MapFromMachineUser(in  s name,
                         in  u uid_inner,
                         out u uid_outer);
      MapToMachineUser(in  u uid_outer,
                       out s machine_name,
                       out o machine_path,
                       out u uid_inner);
      MapFromMachineGroup(in  s name,
                          in  u gid_inner,
                          out u gid_outer);
      MapToMachineGroup(in  u gid_outer,
                        out s machine_name,
                        out o machine_path,
                        out u gid_inner);
    signals:
      MachineNew(s machine,
                 o path);
      MachineRemoved(s machine,
                     o path);
    properties:
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
      readonly s PoolPath = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
      readonly t PoolUsage = \&.\&.\&.;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
      readonly t PoolLimit = \&.\&.\&.;
  };
  interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
  interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
  interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
};
    
.fi
.if n \{\
.RE
.\}











































.SS "Methods"
.PP
\fBGetMachine()\fR
may be used to get the machine object path for the machine with the specified name\&. Similarly,
\fBGetMachineByPID()\fR
gets the machine object the specified PID belongs to if there is any\&.
.PP
\fBGetImage()\fR
may be used to get the image object path of the image with the specified name\&.
.PP
\fBListMachines()\fR
returns an array of all currently registered machines\&. The structures in the array consist of the following fields: machine name, machine class, an identifier for the service that registered the machine and the machine object path\&.
.PP
\fBListImages()\fR
returns an array of all currently known images\&. The structures in the array consist of the following fields: image name, type, read\-only flag, creation time, modification time, current disk space, and image object path\&.
.PP
\fBCreateMachine()\fR
may be used to register a new virtual machine or container with
\fBsystemd\-machined\fR, creating a scope unit for it\&. It accepts the following arguments: a machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the service that registers the machine, a class string, the PID of the leader process of the machine, an optional root directory of the container, and an array of additional properties to use for the scope registration\&. The virtual machine name must be suitable as a hostname, and hence should follow the usual DNS hostname rules, as well as the Linux hostname restrictions\&. Specifically, only 7 bit ASCII is permitted, a maximum length of 64 characters is enforced, only characters from the set
"a\-zA\-Z0\-9\-_\&."
are allowed, the name may not begin with a dot, and it may not contain two dots immediately following each other\&. Container and VM managers should ideally use the hostname used internally in the machine for this parameter\&. This recommendation is made in order to make the machine name naturally resolvable using
\fBnss-mymachines\fR(8)\&. If a container manager needs to embed characters outside of the indicated range, escaping is required, possibly using
"_"
as the escape character\&. Another (somewhat natural) option would be to utilize Internet IDNA encoding\&. The UUID is passed as a 32 byte array or, if no suitable UUID is available, an empty array (zero length) or zeroed out array shall be passed\&. The UUID should identify the virtual machine/container uniquely and should ideally be the same UUID that
/etc/machine\-id
in the VM/container is initialized from\&. The service string can be free\-form, but it is recommended to pass a short lowercase identifier like
"systemd\-nspawn",
"libvirt\-lxc"
or similar\&. The class string should be either
"container"
or
"vm"
indicating whether the machine to register is of the respective class\&. The leader PID should be the host PID of the init process of the container or the encapsulating process of the VM\&. If the root directory of the container is known and available in the host\*(Aqs hierarchy, it should be passed\&. Otherwise, pass the empty string instead\&. Finally, the scope properties are passed as array in the same way as to PID1\*(Aqs
\fBStartTransientUnit()\fR
method\&. Calling this method will internally register a transient scope unit for the calling client (utilizing the passed scope_properties) and move the leader PID into it\&. The method returns an object path for the registered machine object that implements the
org\&.freedesktop\&.machine1\&.Machine
interface (see below)\&. Also see the
\m[blue]\fBNew Control Group Interfaces\fR\m[]\&\s-2\u[1]\d\s+2
for details about scope units and how to alter resource control settings on the created machine at runtime\&.
.PP
\fBRegisterMachine()\fR
is similar to
\fBCreateMachine()\fR\&. However, it only registers a machine and does not create a scope unit for it\&. Instead, the caller\*(Aqs unit is registered\&. We recommend to only use this method for container or VM managers that are run multiple times, one instance for each container/VM they manage, and are invoked as system services\&.
.PP
\fBCreateMachineWithNetwork()\fR
and
\fBRegisterMachineWithNetwork()\fR
are similar to
\fBCreateMachine()\fR
and
\fBRegisterMachine()\fR
but take an extra argument: an array of network interface indices that point towards the virtual machine or container\&. The interface indices should reference one or more network interfaces on the host that can be used to communicate with the guest\&. Commonly, the passed interface index refers to the host side of a "veth" link (in case of containers), a "tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the VM/container interfaces\&. Specifying this information is useful to enable support for link\-local IPv6 communication to the machines since the scope field of sockaddr_in6 can be initialized by the specified ifindex\&.
\fBnss-mymachines\fR(8)
makes use of this information\&.
.PP
\fBKillMachine()\fR
sends a UNIX signal to the machine\*(Aqs processes\&. As its arguments, it takes a machine name (as originally passed to
\fBCreateMachine()\fR
or returned by
\fBListMachines()\fR), an identifier that specifies what precisely to send the signal to (either
"leader"
or
"all"), and a numeric UNIX signal integer\&.
.PP
\fBTerminateMachine()\fR
terminates a virtual machine, killing its processes\&. It takes a machine name as its only argument\&.
.PP
\fBGetMachineAddresses()\fR
retrieves the IP addresses of a container\&. This method returns an array of pairs consisting of an address family specifier (\fBAF_INET\fR
or
\fBAF_INET6\fR) and a byte array containing the addresses\&. This is only supported for containers that make use of network namespacing\&.
.PP
\fBGetMachineOSRelease()\fR
retrieves the OS release information of a container\&. This method returns an array of key value pairs read from the
\fBos-release\fR(5)
file in the container and is useful to identify the operating system used in a container\&.
.PP
\fBOpenMachinePTY()\fR
allocates a pseudo TTY in the container and returns a file descriptor and its path\&. This is equivalent to transitioning into the container and invoking
\fBposix_openpt\fR(3)\&.
.PP
\fBOpenMachineLogin()\fR
allocates a pseudo TTY in the container and ensures that a getty login prompt of the container is running on the other end\&. It returns the file descriptor of the PTY and the PTY path\&. This is useful for acquiring a pty with a login prompt from the container\&.
.PP
\fBOpenMachineShell()\fR
allocates a pseudo TTY in the container, as the specified user, and invokes the executable at the specified path with a list of arguments (starting from argv[0]) and an environment block\&. It then returns the file descriptor of the PTY and the PTY path\&.
.PP
\fBBindMountMachine()\fR
bind mounts a file or directory from the host into the container\&. Its arguments consist of a machine name, the source directory on the host, the destination directory in the container, and two booleans, one indicating whether the bind mount shall be read\-only, the other indicating whether the destination mount point shall be created first, if it is missing\&.
.PP
\fBCopyFromMachine()\fR
copies files or directories from a container into the host\&. It takes a container name, a source directory in the container and a destination directory on the host as arguments\&.
\fBCopyToMachine()\fR
does the opposite and copies files from a source directory on the host into a destination directory in the container\&.
.PP
\fBRemoveImage()\fR
removes the image with the specified name\&.
.PP
\fBRenameImage()\fR
renames the specified image\&.
.PP
\fBCloneImage()\fR
clones the specified image under a new name\&. It also takes a boolean argument indicating whether the resulting image shall be read\-only or not\&.
.PP
\fBMarkImageReadOnly()\fR
toggles the read\-only flag of an image\&.
.PP
\fBSetPoolLimit()\fR
sets an overall quota limit on the pool of images\&.
.PP
\fBSetImageLimit()\fR
sets a per\-image quota limit\&.
.PP
\fBMapFromMachineUser()\fR,
\fBMapToMachineUser()\fR,
\fBMapFromMachineGroup()\fR, and
\fBMapToMachineGroup()\fR
may be used to map UIDs/GIDs from the host user namespace to a container user namespace or vice versa\&.
.SS "Signals"
.PP
\fBMachineNew\fR
and
\fBMachineRemoved\fR
are sent whenever a new machine is registered or removed\&. These signals carry the machine name and the object path to the corresponding
org\&.freedesktop\&.machine1\&.Machine
interface (see below)\&.
.SS "Properties"
.PP
\fIPoolPath\fR
specifies the file system path where images are written to\&.
.PP
\fIPoolUsage\fR
specifies the current usage size of the image pool in bytes\&.
.PP
\fIPoolLimit\fR
specifies the size limit of the image pool in bytes\&.
.SH "MACHINE OBJECTS"
.sp
.if n \{\
.RS 4
.\}
.nf
node /org/freedesktop/machine1/machine/rawhide {
  interface org\&.freedesktop\&.machine1\&.Machine {
    methods:
      Terminate();
      Kill(in  s who,
           in  i signal);
      GetAddresses(out a(iay) addresses);
      GetOSRelease(out a{ss} fields);
      GetUIDShift(out u shift);
      OpenPTY(out h pty,
              out s pty_path);
      OpenLogin(out h pty,
                out s pty_path);
      OpenShell(in  s user,
                in  s path,
                in  as args,
                in  as environment,
                out h pty,
                out s pty_path);
      BindMount(in  s source,
                in  s destination,
                in  b read_only,
                in  b mkdir);
      CopyFrom(in  s source,
               in  s destination);
      CopyTo(in  s source,
             in  s destination);
      OpenRootDirectory(out h fd);
    properties:
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s Name = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly ay Id = [\&.\&.\&.];
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly t Timestamp = \&.\&.\&.;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly t TimestampMonotonic = \&.\&.\&.;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s Service = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s Unit = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly u Leader = \&.\&.\&.;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s Class = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s RootDirectory = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly ai NetworkInterfaces = [\&.\&.\&.];
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
      readonly s State = \*(Aq\&.\&.\&.\*(Aq;
  };
  interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
  interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
  interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
};
    
.fi
.if n \{\
.RE
.\}
























.SS "Methods"
.PP
\fBTerminate()\fR
and
\fBKill()\fR
terminate/kill the machine\&. These methods take the same arguments as
\fBTerminateMachine()\fR
and
\fBKillMachine()\fR
on the Manager interface, respectively\&.
.PP
\fBGetAddresses()\fR
and
\fBGetOSRelease()\fR
get the IP address and OS release information from the machine\&. These methods take the same arguments as
\fBGetMachineAddresses()\fR
and
\fBGetMachineOSRelease()\fR
of the Manager interface, respectively\&.
.SS "Properties"
.PP
\fIName\fR
is the machine name as it was passed in during registration with
\fBCreateMachine()\fR
on the manager object\&.
.PP
\fIId\fR
is the machine UUID\&.
.PP
\fITimestamp\fR
and
\fITimestampMonotonic\fR
are the realtime and monotonic timestamps when the virtual machines where created in microseconds since the epoch\&.
.PP
\fIService\fR
contains a short string identifying the registering service as passed in during registration of the machine\&.
.PP
\fIUnit\fR
is the systemd scope or service unit name for the machine\&.
.PP
\fILeader\fR
is the PID of the leader process of the machine\&.
.PP
\fIClass\fR
is the class of the machine and is either the string "vm" (for real VMs based on virtualized hardware) or "container" (for light\-weight userspace virtualization sharing the same kernel as the host)\&.
.PP
\fIRootDirectory\fR
is the root directory of the container if it is known and applicable or the empty string\&.
.PP
\fINetworkInterfaces\fR
contains an array of network interface indices that point towards the container, the VM or the host\&. For details about this information see the description of
\fBCreateMachineWithNetwork()\fR
above\&.
.PP
\fIState\fR
is the state of the machine and is one of
"opening",
"running", or
"closing"\&. Note that the state machine is not considered part of the API and states might be removed or added without this being considered API breakage\&.
.SH "EXAMPLES"
.PP
\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.machine1\&.Manager on the bus\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ gdbus introspect \-\-system \e
  \-\-dest org\&.freedesktop\&.machine1 \e
  \-\-object\-path /org/freedesktop/machine1
      
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&2.\ \&Introspect org\&.freedesktop\&.machine1\&.Machine on the bus\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ gdbus introspect \-\-system \e
  \-\-dest org\&.freedesktop\&.machine1 \e
  \-\-object\-path /org/freedesktop/machine1/machine/rawhide
      
.fi
.if n \{\
.RE
.\}
.SH "VERSIONING"
.PP
These D\-Bus interfaces follow
\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&.
.SH "NOTES"
.IP " 1." 4
New Control Group Interfaces
.RS 4
\%https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/
.RE
.IP " 2." 4
the usual interface versioning guidelines
.RS 4
\%http://0pointer.de/blog/projects/versioning-dbus.html
.RE
